Devpac Falcon Library
		
			Manual
			
			
Following are short descriptions of all included routines. Most are
subroutines and should be called with 'bsr' or 'jsr' unless the word
macro follows the routine name in which case it is a macro. If a
routine says 'destroys a lot' then you should save all the registers
you are using except a7 which is never ruined. Some routine descriptions
even contains an example, so hopefully there will be no problems
understanding them.


*
* CACHE.S
*
*	Cache equates. You'll need devpac 3 for this one I think.
*	Here they are:
*
*	 ENABLE_CACHE		EQU 1   ; Enable instruction cache
*	 FREEZE_CACHE		EQU 2   ; Freeze instruction cache
*	 CLEAR_INST_CACHE_ENTRY	EQU 4   ; Clear instruction cache entry
*	 CLEAR_INST_CACHE	EQU 8   ; Clear instruction cache
*	 INST_BURST_ENABLE	EQU 16  ; Instruction burst enable
*	 ENABLE_DATA_CACHE	EQU 256 ; Enable data cache
*	 FREEZE_DATA_CACHE	EQU 512 ; Freeze data cache
*	 CLEAR_DATA_CACHE_ENTRY	EQU 1024 ; Clear data cache entry
*	 CLEAR_DATA_CACHE	EQU 2048 ; Clear data cache
*	 DATA_BURST_ENABLE	EQU 4096 ; Instruction burst enable
*	 WRITE_ALLOCATE		EQU 8192 ; Write allocate 
*
* ex.	move.l	#ENABLE_CACHE+ENABLE_DATA_CACHE+WRITE_ALLOCATE,d0
*	movec	d0,CACR		; turns on the caches
*

*
* CLS.S
*
*	@cls???
*	 clears ??? bytes.
* In	 a0.l=start address
*	 (destroys a lot)
*
*	??? supported:	184320 (384*240*16bp)
*			92160  (384*240*8bp)
*			32000  (st modes)
* ex.	 bsr @cls92160
*

*
* CONVPAL1.S
*
*	@convert_stpal
*
*	Convert an old st colour value to a new falcon one
*
* In	d0.w=old st colour
* Out	d0.l=falcon colour
*	(destroys d1-d3)
*

*
* COOKIE.S
*
*	@getcookie
*
*	Finds and returns a Cookie. Supervisor only!
*
* In	d1.l=Cookie name
* Out	d0.l=Cookie value or -1
*	(destroys a0)
*

*
* DSPMOD.S
*
*	@dsp_play
*
*	Sets interupts and plays some soundtracker music. Modules mustn't have 
*	more than 4 voices. Supervisor only.
*
* In	a0.l=Module adr.
*	(destroys a lot)
*
*	@dsp_stop
*
*	Stops playing the music and restores interupts.
*	Supervisor only.
*	(destroys a lot)
*

*
* EXIT.S
*
*	@exitifspace  macro
*	 branches to exit if space has been pressed. Supervisor only!
*	 (destroys nothing)
*

*
* GEM.S
*
*	@gemdos	macro
* In	 #functionnbr, #stackcorrection
* ex.	 @gemdos 1,2	;waits for a key
*
*	@xbios	macro
* In	 #functionnbr, #stackcorrection
* ex.	 @xbios 37,2	;waits for vsync
*
*	@gem	macro
* In	 #functionnbr, #trapnbr, #stackcorrection
* ex.	 @gem 1,1,2	;waits for a key
*

*
* GETPAR.S	(include right after releasem.s)
*
*	Gets all parameters sent to the program.
*	Must be directly after releasem.
*
* Out	a0.l=Address where the parameters are kept
*
* ex.	include	releasem.s	release unused memory, this is line nr 1 of the program
*	include	getpar.s	get adr. where the parameters are kept
*	move.l a0,paradr	save the result
*
*	paradr ds.l 1
*

*
* GORAUD.S
*
*	@goraud
*
*	Draw a goraud shaded polygon in true colour.
*	There's no clipping so don't draw too large polygons.
*	Call @initgoraud once before using this one!
*
* In	a1.l=screenadr
*	a2.l=adr to colourtable
*	new_crds=following table: [x,y,i]*nbr_of_points
*	d6.w=nbr. of points
*	xres equ horizontal resolution
*	(destroys a lot)
*
*	The colourtable consists of 32 words, each a true colour value.
*	 word nr 0 is the darkest and word nr 31 the brightest. This is
*	 followed by 16 empty words.
*	Supplied colours: g_lightred, g_green, g_brown, g_white
*	new_crds is a table that consist of a pair of coordinates followed
*	 by a brightnes factor. The brightnes factor is a number between 0
*	 and #$7fff.
*
* ex.	 xres equ 384		overscaned lowres screen
*	 bsr @initgoraud	call once only
*
*	 move.l scradr,a1	screenaddress
*	 move.l #g_red,a2	I want a red poly
*	 moveq #4,d6		four points
*	 bsr @goraud		draw it
*
*	 new_crds dc.w 10,10,0		a dark point
*          	  dc.w 200,20,$7fff	a bright point
*		  dc.w 140,140,$7fff/2
*		  dc.w 25,50,$7fff/4
*	
*
*	@initgoraud
*	 This subroutine must be called once before using @goraud.
*

*
* HLINE1.S
*
*	@drawhline1
*
*	Draws a horizontal line in 8 bitplane mode. Clipping is implemented.
*	This routine only uses the six first bitplanes.
*
* In	a0.l=screenadr d0=xmin d1=xmax
*	d2.l - d4.l =6 bitplanes
*	xres equ  horizontal screen resolution
*	(destroys d0-d7/a0-a1)
*
* ex.	 move.l	screen+xres*50,a0	ypos=50
*	 move #-34,d0		left xcord
*	 move #67,d1		right xcord
*	 move.l #$0,d2		don't set bitplane 0 or 1
*	 move.l	#$0000ffff,d3	set bitplane 3
*	 move.l	#$ffffffff,d4	set bitplane 4 and 5
*	 bsr @drawhline1
*

*
* ICE.S
*
*	@icedecrunch
*
*	Checks if the data is icepacked and possibly unpacks it.
*
* In	a0.l=Data adr.
*

*
* LOADFILE.S
*
*	@loadfile
*
*	Loads a file and possibly unpacks it (ice 2.40).
*
* In	a5.l=adr. to a filename terminated by zero
*	a6.l=dest.
*	d7.l=filelength
*	(destroys a lot)
*	

*
* RELEASEM.S
*
*	This routine releases all memory not needed by the program.
*	Include this rout at the top of your program and the memory
*	will be relesed properly.
*
* ex.	include	releasem.s	release unused memory, this is line nr 1 of the program
*

*
* SAVEFILE.S
*
*	@savefile
*
*	Saves data as a file.
*
* In	a5.l=adr. till nollavslutat filnamn
*	a6.l=source
*	d7.l=fill„ngd
*	(destroys a lot)
*

*
* SETFV.S
*
*	@setfv
*	 Sets the falcon video registers. The data that is
*	 written to the video registers must be a .FV (Falcon Video)
*	 file. Supervisor only.
* In	 a0.l=adr. to Falcon Video data
* Out	 d0.l: 0=no error  -1=error, no .FV data
*	 (destroys d0-d2/a0-a2)
*
*	@savefv
*	 Saves the falcon video registers to memory. Supervisor only.
*	 (destroys a0-a1)
*
*	@resorefv
*	 Restores the saved falcon video registers. Supervisor only.
*	 (destroys d0-d2/a0-a2)
*

*
* SETVIDEO.S
*
*	@setvideo
*	 Save and set resolution.
* In	 d7.w=mode
*  modeequates: vertflag, stmodes, overscan, pal, vga, col80, bps1-16
*	 (xbios, destroys d0-d2/a0-a2)
* ex.	 move #pal+bps16,d7
*	 bsr @setvideo
*
*	@restorevideo
*	 Restores the saved resolution.
*	 (xbios, destroys d0-d2/a0-a2)
*
*	@setvadr
*	 Sets the physical and logical screenadress.
* In	 d0.l=screenadr.
*	 (xbios, destroys d0-d2/a0-a2)
*
*	@savevadr
*	 Saves the current screenadr.
*	 (xbios, destroys d0-d2/a0-a2)
*
*	@restorevadr
*	 Restores the saved screenadr.
*	 (xbios, destroys d0-d2/a0-a2)
*

*
* SHRTONES.S
*
*	@super
*	 enter supervisor mode  (gemdos($20), destroys d0-d1/a0-a1)
*
*	@user
*	 returns to user mode  (gemdos($20), destroys d0-d1/a0-a1)
*
*	@waitvbl
*	 waits for a vertical blank  (xbios(#37), destroys d0-d2/a0-a2)
*
*	@waitkey
*	 waits for a keypress, no echo  (gemdos(#7), destroys a0)
* Out	 d0.b=ascii value
*
*	@exitifkey
*	 quits if a key has been pressed
*	 (gemdos(#11,#7,#0), destroys a0)
*
*	@quit
*	 terminate process  (gemdos(#0))
*

*
* TIMER.S
*
*	@colour[#value.l]  macro
*	 sets backround colour to value. Supervisor only!
*	 (destroys nothing)
*

*
* TRIG.S
*
*	All results are taken from a 1440 entries large lookup table.
*
*	@sin
*	 Returns the sine of an angle.
* In	 d0.w=angle in degrees with six decimal bits (the legal values are 0-$59ff or 0-359.999 degrees)
* Out	 d1.w=sin(angle), a word with one sign bit and 15 decimal bits.
*	 (destroys d0/a0)
*
*	@cos
*	 Returns the cosine of an angle.
* In	 d0.w=angle in degrees with six decimal bits (the legal values are 0-$59ff or 0-359.999 degrees)
* Out	 d1.w=sin(angle), a word with one sign bit and 15 decimal bits.
*	 (destroys d0/a0)
*
* ex.	move #180*64,d0		; make it 180 degrees
*	bsr @sin		; d1 will now contain 0
*	move #180*64,d0		; d0 is destroyed so we had better enter the value again
*	bsr @cos		; d1 will now contain -1 ($8000)
*

*
* WINDOW.S
*  (vdilib.i & aeslib.i must be included at the end of the program)
*
*	@createwindow
*
*	Creates and opens a simple gem window.
*	The size (xwidth,ywidth) is the workarea of the window.
*
* In	wtype equ %info move full close name
*	xstart,ystart,xwidth,ywidth,windowname(string terminated by 0)
* Out	w_handle,ap_id
*	(destroys a lot)
*
*	@recalcwindow
*	 Recalculates the window size.
*	 (destroys a lot)
*
*	@moveit
*	 Moves the window. May be called at every vm_moved(=28) event.
* In	 a0.l=adr to messagebuffer
*	 (destroys a lot)
*
*	@drawrsrc
*	 Draws the rsrc.
*	 This function doesn't care about clipping, so you should probably not use it.
* In	 a0.l=adr to rsrc
*	 (destroys a lot)
*
*	@updatersrc
*	 Draws the rsrc. Use this when receiving update events(=20).
*	 This function takes care of all clipping.
* In	 a0.l=adr to rsrc
*	 (destroys a lot)
*
*	@topwindow
*	 Activates the window. May be called at every vm_topped(=21) event.
* In	 a0.l=adr to messagebuffer
*	 (destroys a lot)
*
*	@bottomwindow
*	 Bottoms the window if it's mine. May be called at every vm_bottomed(=33) event.
* In	 a0.l=adr to messagebuffer 
*	 (destroys a lot)
*
*	@button
*	 Returns the object number that was clicked on. This function may be called
*	 at every mousebutton event.
* In	 a0.l=adr. to rsrc
*	 (It automatically takes the x and y coordinates from int_out)
* Out	 d0.w=object that was pressed or -1.
*	 (destroys a lot)
*
*	@loadrsrc
*	 Loads a resource file and creates a window containg the object in the
*	 file. You don't have to call @createwindow if you use @loadrsrc.
* In	 wtype equ %info move full close name
*	 windowname(string terminated by 0)
* 	 a0.l=address to a nul terminated filename
* Out	 a0.l=address to the resource data
*	 (destroys a lot)
*

*
* WINEVENT.S
*
*	@dowindowevents
*	 For the lazy one. This function waits for events and takes care of
*	 everything but the close button or if someone clicked on an object.
*	 If one of these events occur the program branches to closeevent
*	 or buttonevent. Those subroutines you have to make yourself.
* In	 a0.l=adr. to rsrc
*	 w_handle, ap_id  (These are created automatically if you use @createwindow)
* Out	 buttonevent: d0.w=number of the object pressed
*	 closeevent: nothing
*	 (destroys a lot)
*
* ex.	;create a window;
*	move.l rsrcadr,a0
*	bra @dowindowevents	; it will never return so you may use 'bra' or 'jmp'
*
* buttonevent		; d0.w will contain the object that was pressed
*	cmp #1,d0 	; was it my button?
* 	beq mybutton	; yes!
*	rts		; no!
*
* closeevent
*	bsr @exitwindow	; close window
*	(rsrc_free)	; only if you have used @loadrsrc
*	bra @quit	; quit
*